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An API is a contract 


Changing our API 








Versioning 


/ap1/v1/documents 
/ap1/v2/documents 


/ap1/v3/documents 
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We recommend you start moving away from analytics vO endpoints to the newly introduced analytics v1 
Trends endpoints as soon as possible. As per our Version 1 Announcement, v0 will be deprecated on June 30, 
2016. 
Geo 
Ads Consolidation of analytics endpoints 
General 


In version O of the Ads API, a separate analytics endpoint existed for each entity type, from funding 
Analytics instruments to promoted tweets to organic tweets. With version 1 of the API, we've consolidated these into 
just two endpoints - one for synchronous stats queries, and another for asynchronous stats queries. These 
two endpoints can be used to fetch stats for all entity types, specified using the entity and entity ids 
Campaign Management parameters. The synchronous endpoint will return smaller batches of data ideal for real-time campaign 
optimizations. The asynchronous endpoint is intended for larger queries of complex data, ideal for 
generating reporting or historical backfills. 


Audiences 


Creatives 





An alternative?” 


API Versioning to make User happy? 





Stable API 


API Versioning to make User happy? 





Documentation 


API Versioning to make User happy? 





Easy to Upgrade 


API Versioning to make User happy? 





Don’t make me think 


Best for us? 


API Versioning to make the Maintainer happy? 





Easy to change 


API Versioning to make the Maintainer happy? 





Easy to maintain 


API Versioning to make the Maintainer happy? 





Incentive to upgrade 


Support all the versions! 
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APIs as infrastructure: future-proofing Stripe 
with versioning 


Brandur Leach on August 15, 2017 in Engineering 


When it comes to APIs, change isn't popular. While software developers are used to 
iterating quickly and often, API developers lose that flexibility as soon as even one 
user starts consuming their interface. Many of us are familiar with how the Unix 
operating system evolved. In 1994, The Unix-Haters Handbook was published 
containing a long list of missives about the software—everything from overly-cryptic 
command names that were optimized for Teletype machines, to irreversible file 
deletion, to unintuitive programs with far too many options. Over twenty years later, 
an overwhelming majority of these complaints are still valid even across the dozens 
of modern derivatives. Unix had become so widely used that changing its behavior 
would have challenging implications. For better or worse, it established a contract 


with its users that defined how Unix interfaces behave. 





How does this work for the 
user? 


User's first API Call 
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Existing User's API Call 
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Existing User's API Call - custom version 
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How to build it? 


Our Implementation 





Keep It current 


Our Implementation 





Release rolling versions 


Our Implementation 





Versions as 
transformations 
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LATEST VERSION (VERSION 7) 
| Es) API Application 


Implementation 





connection 

|> endpoint 
|> router 

|> pipeline 
I> controller 


connection 

|> endpoint 
|> plug 

|> router 

|> plug 

|> pipeline 
|> controller 


connection 

|> endpoint 

|> authentication 
|> router 

|> apply version 
|> pipeline 

|> controller 


Sample application 


curl -X GET -G http://0.0.0.0:4000/api/todos --data 'size=2' 


curl -X GET http://0.0.0.0:4000/api/todos --data 'size=2' 


{ 


"data": [ 
{ 
"title": "Build Sample App", 
"20": 1, 
"description": "Put together a sample app for versioning" 
}; 
{ 
"title": "Add documentation", 
"id": 2, 
"description": "Write up some documentation" 
} 


curl -X GET -G http://0.0.0.0:4000/api/todos \ 
-data |'size=2'| 






curl BC -G EBD 0.0.0:4000/api/todos \ 





OLD VERSION VERSION 


| a API User 
°° %Plug.Conn{params: %{"size" => size}} 
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OLD REQUEST FORMAT 





%Plug.Conn{params: %{''page_ size" => size}} 


LATEST VERSION 


| 3+ API Application 


defmodule TodosWeb.Plugs.ModifyRequest do 
@behaviour Plug 


def init(opts), do: opts 


def call(%Plug.Conn{params: %{"size"=> size} = params} = conn, _) do 
updated_params = 
params 
|> Map.put("page_size", size) 
|> Map.delete("size") 


%{conn | params: updated params T 
end 
def call(conn, _), do: conn 


end 


curl -X GET http://0.0.0.0:4000/api/todos 


{ 
"data": [ 
{ 
"title": "Build Sample App", 
"20": 1, 
"description": "Put together a sample app for versioning" 
}; 
{ 
"title": "Add documentation", 
"id": 2, 
"description": "Write up some documentation" 
} 


{ 


"title": "Add documentation", 
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"Write up documentation" 





"title": "Add documentation", 
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"Write up documentation" 





LATEST VERSION 
ee] API Application 
+ 


CURRENT RESPONSE FORMAT 


{ 
"title": "Add documentation", 
+ ms ULI 
o id”: 2, 
a? “details”: "Write up documentation" 
+ T 
Transform + y 
E 
Response , 
* OLD RESPONSE FORMAT 
Ca { 
A "title": "Add documentation", 
"id": 2, 
“description”: "Write up documentation" 


} 


+ 


OLD VERSION VERSION 


a API User 


defmodule TodosWeb.Plugs.TransformResponse do 
@behaviour Plug 


def init(opts), do: opts 


def call(%Plug.Conn{resp_body: body} = conn, _opts) do 
Plug.Conn.register_before_send(conn, fn conn -> 
transform_description(conn) 
end) 
end 
def call(conn, _), do: conn 


defp transform_description(%Plug.Conn{resp_ body: body} = conn) do 
end 
end 


defmodule TodosWeb.Plugs.TransformResponse do 
@behaviour Plug 


def init(opts), do: opts 


def call(%Plug.Conn{resp_body: body} = conn, _opts) do 
Plug.Conn.register_before_send(conn, fn conn -> 
transform_description(conn) 
end) 
end 
def call(conn, _), do: conn 


defp transform description(2Plug.Conniresp_body: body} = conn) do 
end 
end 


defp transform_description(%Plug.Connfresp_body: body} = conn) do 
json_body = Poison.decode! (body) 


transformed_data = 
json_body["data"] 
|> Enum.map(fn(item) -> 
|> Map.put("details", item["description"]) 
|> Map.delete("description") 
end) 


%{conn | resp body: Poison.encode! (*(json_body | "data" => transformed_data}) } 
end 


defp transform description(%Plug.Conn{resp_ body: b 
transformed body = 
body 
|> to string 
|> String.replace("\"description\":", "\"details\":") 





%{conn | resp body: transformed_body T 
end 


OLD VERSION VERSION 





| Q API User 
OLD REQUEST FORMAT OLD RESPONSE FORMAT 
%Plug.Conn{params: %{"size" => size}} %Plug.Conn{resp_body: body} 
CURRENT REQUEST CURRENT RESPONSE 
%Plug.Conn{params: %{"page_size" => size}} %Plug.Conn{resp_body: body} 

















LATEST VERSION 


| fs} API Application 


defmodule TodosWeb.Change do 


(0006 181 818 
Transforms the request on the way into the application. 


@callback transform_request(Plug.Conn.t) :: Plug.Conn.t 


(0006 18 LE LL 
Registers callback to transform response on the way out 
of the application 


@callback transform_response(Plug.Conn.t) :: Plug.Conn.t 


end 


defmodule TodosWeb.Changes .Versions do 


@all_versions %{ 

"2017-10-02" => [ 

TodosWeb. Changes.RevertMultipleAuthors 

1, 

"2017-10-03" => [ 
TodosWeb.Changes.RemoveDocumentLocation, 
TodosWeb. Changes. RenameSourceId 

1, 

"2017-10-04" => [ 

TodosWeb. Changes. ResetSourceReachDefault 


end 


defmodule TodosWeb.Changes .Versions do 


def changes_for(requested_version) do 
@all_versions 
|> versions_since(requested_version) 
|> Keyword. values 
|> List. flatten 

end 


defp versions since(versions, requested version) do 


Enum. filter(versions, fn({version_date, _changes}) -> 
requested_version <= version_date 
end) 
end 


end 


connection 

|> endpoint 

|> authentication 
|> router 

|> apply version 
|> pipeline 

|> controller 


defmodule TodosWeb.Plugs.ApplyVersion do 
@behaviour Plug 


def init(opts), do: opts 

def call(conn, _) do 
#1. get request version 
# 2. get changes for version 
# 3. apply request changes 
# 4. apply response changes 


end 
end 


defmodule TodosWeb.Plugs.ApplyVersion do 
@behaviour Plug 


def init(opts), do: opts 


def call(conn, _) do 
changes = 
get_req_header(conn, "x-api-version") 
|> List. first() 
|> TodosWeb.Versions.changes_for() 


# apply request changes 

Enum. reduce(changes, conn, fn change, conn -> 
change. transform_request (conn) 

end) 


# apply response changes 
Enum. reduce(changes, conn, fn change, conn -> 
Plug.Conn. register before send(conn, fn conn -> 
change. transform response(conn) 
end) 
end) 


end 
end 


defmodule TodoAPI.Plugs.ApplyVersion do 
@behaviour Plug 


def init(opts), do: opts 


def call(conn, _) do 
changes = # should handle invalid versions 
get_reg_header(conn, "x-api-version") 
|> List.first() 
|> TodoAPI.Versions.changes_for() 


# apply request changes 

Enum.reduce(changes, conn, fn change, conn -> 
change.transform_request(conn) 

end) 


# apply response changes 
Enum. reduce(changes, conn, fn change, conn -> 
Plug.Conn. register before send(conn, fn conn -> 
change. trans form_response(conn) 
end) 
end) 


end 
end 


defmodule TodoAPI.Plugs.ApplyVersion do 
@behaviour Plug 


def init(opts), do: opts 


def call(conn, _) do 
changes = 
get_reg_header(conn, "x-api-version") 
|> List.first() 
|> TodoAPI.Versions.changes_for() 


# apply request changes 

Enum. reduce(changes, conn, fn change, conn -> 
change. transform_request (conn) 

end) 


# apply response changes 
Enum.reduce(changes, conn, fn change, conn -> 
Plug.Conn.register_before_send(conn, fn conn -> 
change. trans form_response(conn) 
end) 
end) 


end 
end 
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<> Code Issues 0 Pull requests 0 Insights 


Elixir package that allows to add compatibility layers via API gateways. https://hex.pm/packages/multiverse 





api plug elixir hex versioning gateways elixir-lang 

51 commits P 1 branch © 7 releases 22 2 contributors sj MIT 
Branch: master + New pull request Create new file Upload files Find file Clone or download + 
Eh AndrewDryga Format the code with Elixir 1.6 formatter Latest commit 83b89dc 13 days ago 


README.md 


Multiverse 


This plug helps to manage multiple API versions based on request and response gateways. This is an awesome 
practice to hide your backward compatibility. It allows to have your code in a latest possible version, without 
duplicating controllers or models. 





What makes a happy API User? 





Stable API 
Documentation 
Don’t make me think 


Easy to upgrade 


What makes an API Maintainer happy? 





Easy to change 
Keep it manageable 


Incentive to upgrade 





Why doesn’t everyone do this? 


Conclusion 


@niallburkley | github.com/nburkley | niallburkley.com 


Danke! 
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